Skip to content

Add _reload directive support for config reload framework.#13110

Open
brbzull0 wants to merge 3 commits intoapache:masterfrom
brbzull0:config_reload_add_directives
Open

Add _reload directive support for config reload framework.#13110
brbzull0 wants to merge 3 commits intoapache:masterfrom
brbzull0:config_reload_add_directives

Conversation

@brbzull0
Copy link
Copy Markdown
Contributor

@brbzull0 brbzull0 commented Apr 21, 2026

Add _reload directive support to config reload framework

TL;DR

Adds a generic way to pass operational parameters to config reload handlers.
Instead of per-config flags added to traffic_ctl, handlers now receive directives
via a reserved _reload key that the framework extracts automatically.

traffic_ctl config reload -D virtualhost.id=myhost.example.com

Handlers read directives with ctx.reload_directives()["id"], while
ctx.supplied_yaml() stays clean (content only, no directives). Also fixes a bug
where stale RPC-supplied config data could replay on subsequent file-based reloads.


Summary

Config handlers sometimes need operational parameters that modify how a reload
is performed — for example, scoping a reload to a single entry by ID, or some other key to pass.
Currently there's no standard way to pass these parameters;
PR #13108 (virtualhost) works around this by adding a per-config --virtualhost flag
to traffic_ctl.

This PR adds a generic reload directive mechanism:

  • A reserved _reload key inside each config's YAML node carries directives
  • The framework extracts _reload before invoking the handler
  • traffic_ctl gains a --directive (-D) flag with dot-notation syntax
  • Handlers access directives via ConfigContext::reload_directives()

Motivation

The virtualhost PR (#13108) needs to tell the handler which virtualhost to reload
from file. Without a generic mechanism, every config that needs parameters would require
its own traffic_ctl flag and custom parsing — leading to flag proliferation and
duplicated code.

The _reload directive solves this once for all handlers.

Usage

traffic_ctl CLI

# Reload a specific virtualhost from file
traffic_ctl config reload -D virtualhost.id=myhost

# Multiple directives (space-separated after single -D)
traffic_ctl config reload -D virtualhost.id=myhost virtualhost.foo=bar

# Directives for different handlers in the same reload
traffic_ctl config reload -D virtualhost.id=myhost sni.fqdn=example.com

# Complex directives via -d (full YAML)
traffic_ctl config reload -d 'virtualhost: { _reload: { id: myhost } }'

Wire format

-D virtualhost.id=myhost produces:

{
  "configs": {
    "my_config": {
      "_reload": { "id": "myhost" }
      "param1":{}
    }
  }
}

Handler API

void MyConfig::reconfigure(ConfigContext &ctx) {
    ctx.in_progress();

    if (auto directives = ctx.reload_directives()) {
        if (directives["id"]) {
            std::string id = directives["id"].as<std::string>();
            if (!reload_single_entry(id)) {
                ctx.fail("Unknown entry: " + id);
                return;
            }
            ctx.complete("Reloaded entry: " + id);
            return;
        }
    }

    if (!load_from_file(config_filename)) {
        ctx.fail("Failed to parse " + config_filename);
        return;
    }
    ctx.complete("Loaded from file");
}

Key behavior:

  • reload_directives() returns the extracted _reload YAML map
  • supplied_yaml() is clean — never contains _reload keys
  • Child contexts inherit directives from their parent
  • If _reload is not a YAML map, a warning is logged and directives are ignored

Changes

Framework (src/mgmt/config/)

  • ConfigContext: Added reload_directives() getter, set_reload_directives()
    setter, and propagation to child contexts via add_dependent_ctx()
  • ConfigRegistry::execute_reload(): Extracts _reload from the config's YAML
    node before passing content to the handler. Also fixes a bug where _passed_configs
    entries were not erased after consumption, causing stale RPC data to replay on
    subsequent file-based reloads

CLI (src/traffic_ctl/)

  • traffic_ctl.cc: Added --directive (-D) option to config reload
  • CtrlCommands.cc: Added parse_directive() helper that parses
    config_key.directive_key=value and injects into configs[key]["_reload"][dir] = val

Damian Meden added 2 commits April 21, 2026 14:02
Config handlers need a way to receive operational parameters (e.g.
scoping a reload to a single entry) without conflating them with
config content. This adds a reserved _reload key inside the configs
YAML node that the framework extracts before invoking handlers.

Framework: ConfigContext gains reload_directives() getter; the
_reload node is extracted in ConfigRegistry::execute_reload() and
stripped from supplied_yaml(). Fixes stale _passed_configs entries
not being erased after consumption.

CLI: traffic_ctl config reload gains --directive (-D) flag using
dot-notation (config_key.directive_key=value). Multiple directives
are space-separated after a single -D.

Tests: unit tests for parse_directive and ConfigContext directive
propagation; autest coverage for directive RPC structure handling.

Docs: developer guide and traffic_ctl reference updated.
@brbzull0
Copy link
Copy Markdown
Contributor Author

[approve ci autest 1]

@brbzull0 brbzull0 changed the title [proof of concept] Add _reload directive support for config reload framework. Add _reload directive support for config reload framework. Apr 21, 2026
@brbzull0 brbzull0 self-assigned this Apr 21, 2026
@brbzull0 brbzull0 added Configuration traffic_ctl traffic_ctl related work. labels Apr 21, 2026
@brbzull0
Copy link
Copy Markdown
Contributor Author

[approve ci autest 1]

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR extends the ATS config reload framework to support operational “reload directives” passed via a reserved _reload YAML key, enabling handlers to receive parameters (e.g. scoping by id) separately from config content.

Changes:

  • Add ConfigContext::reload_directives() and propagate directives into dependent contexts.
  • Extract _reload from RPC-supplied YAML in ConfigRegistry::execute_reload() and consume _passed_configs entries to prevent replay.
  • Add traffic_ctl config reload --directive/-D parsing and update docs/tests accordingly.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 10 comments.

Show a summary per file
File Description
src/mgmt/config/ConfigRegistry.cc Consumes passed RPC configs and extracts _reload before handing content to handlers.
include/mgmt/config/ConfigContext.h Adds reload_directives() API and private setter.
src/mgmt/config/ConfigContext.cc Propagates directives to child contexts; implements new accessor/setter.
src/traffic_ctl/traffic_ctl.cc Adds --directive/-D option to config reload.
src/traffic_ctl/CtrlCommands.cc Implements directive parsing and injects into YAML request.
doc/developer-guide/config-reload-framework.en.rst Documents _reload extraction and handler usage.
doc/appendices/command-line/traffic_ctl.en.rst Documents -D CLI wire format and usage.
tests/gold_tests/jsonrpc/config_reload_rpc.test.py Adds JSONRPC gold tests ensuring _reload payloads are handled/rejected appropriately.
src/records/unit_tests/test_ReloadDirectives.cc Adds unit tests for directive parsing and extraction semantics.
src/records/CMakeLists.txt Registers the new unit test in the test target.

Comment thread src/mgmt/config/ConfigRegistry.cc Outdated
Comment thread src/mgmt/config/ConfigRegistry.cc
Comment thread src/traffic_ctl/traffic_ctl.cc
Comment thread doc/developer-guide/config-reload-framework.en.rst
Comment thread include/mgmt/config/ConfigContext.h
Comment thread doc/appendices/command-line/traffic_ctl.en.rst
Comment thread src/traffic_ctl/CtrlCommands.cc
Comment thread src/records/unit_tests/test_ReloadDirectives.cc
Comment thread doc/developer-guide/config-reload-framework.en.rst
Comment thread src/records/unit_tests/test_ReloadDirectives.cc
@brbzull0 brbzull0 marked this pull request as ready for review April 22, 2026 12:07
@brbzull0 brbzull0 added this to the 11.0.0 milestone Apr 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Configuration traffic_ctl traffic_ctl related work.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants